feat: added configurable base directory. by mcking-07 · Pull Request #826 · pingdotgg/t3code

mcking-07 · 2026-03-10T18:12:54Z

What Changed

Added a configurable base directory for T3 Code data storage via:

T3CODE_BASE_DIR environment variable
--base-dir CLI flag

The base directory defaults to ~/.t3, with the following paths now relative to baseDir:

userdata -> application state and SQLite database
worktrees -> git worktree directories (existing, now uses baseDir)

Path precedence:

baseDir: CLI (--base-dir) > env (T3CODE_BASE_DIR) > default (~/.t3)
stateDir: CLI (--state-dir) > env (T3CODE_STATE_DIR) > default (<baseDir>/userdata)

Note: If stateDir is set explicitly (via CLI or env), it takes full priority and can be anywhere, independent of baseDir.

Changes include:

Add baseDir to ServerConfigShape
Add resolveBaseDir() for base directory resolution
Update resolveStateDir() to accept baseDir parameter
Add --base-dir flag to CLI (server + dev-runner)
Add T3CODE_BASE_DIR env var support
Update all test layers to include baseDir

Why

Previously, all T3 Code data (worktrees, userdata, etc.) was hardcoded to ~/.t3. This change introduces T3CODE_BASE_DIR (--base-dir CLI flag) to allow users to customize the base directory.

This enables:

Storing data in a custom location (not ~/.t3)
Using different drives/volumes (external SSD, network mount, etc.)
CI/headless environments with non-standard paths
For users who prefer not to have a .t3 folder in their home directory cough myself cough

Fixes #748

Checklist

This PR is small and focused
I explained what changed and why
I included before/after screenshots for any UI changes
I included a video for animation/interaction changes

Note

Replace `--state-dir`/`T3CODE_STATE_DIR` with `--home-dir`/`T3CODE_HOME` as the configurable base directory

Introduces a baseDir concept (~/.t3 by default) from which all server paths (stateDir, dbPath, attachmentsDir, logsDir, worktreesDir, etc.) are deterministically derived via a new deriveServerPaths util in config.ts.
Renames the CLI flag from --state-dir to --home-dir and the env var from T3CODE_STATE_DIR to T3CODE_HOME across the server, desktop app, dev runner, and documentation.
All internal consumers (attachment resolution, SQLite path, terminal log path, worktree path, telemetry) now read pre-derived paths from ServerConfig instead of constructing paths by joining stateDir at call sites.
ServerConfig.layerTest is updated to accept a prefix option and create a temp base directory, replacing explicit stateDir arguments throughout the test suite.
Risk: T3CODE_STATE_DIR is no longer read; existing overrides using that env var will silently have no effect.

^{Macroscope summarized 1b462fd.}

…` env and --base-dir flag.

coderabbitai · 2026-03-10T18:13:05Z

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 6e656027-8c0a-4f2d-97e2-b39053dffd4b

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

Copilot

Pull request overview

Adds a configurable “base directory” for T3 Code data storage (~/.t3 by default), exposing it via T3CODE_BASE_DIR and a --base-dir CLI flag, and updates the server/dev-runner/test harnesses so state/worktrees paths become relative to this base.

Changes:

Introduce baseDir into server config and CLI/env resolution with documented precedence (--base-dir > T3CODE_BASE_DIR > default).
Move worktree location under <baseDir>/worktrees and make default state dir relative to base (<baseDir>/userdata).
Update dev-runner + extensive test layers/harnesses to pass and use baseDir.

Reviewed changes

Copilot reviewed 20 out of 20 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
turbo.json	Adds `T3CODE_BASE_DIR` to turbo global env passthrough.
scripts/dev-runner.ts	Adds base dir flag/env support and resolves derived dev state dir.
scripts/dev-runner.test.ts	Updates dev-runner env tests for new base dir behavior.
apps/server/src/wsServer.test.ts	Extends test server options to include `baseDir`.
apps/server/src/telemetry/Layers/AnalyticsService.test.ts	Updates test config layer to pass `baseDir`.
apps/server/src/provider/Layers/CodexAdapter.test.ts	Updates `ServerConfig.layerTest` calls for new signature.
apps/server/src/os-jank.ts	Adds `resolveBaseDir` + updates `resolveStateDir` to be base-dir aware.
apps/server/src/orchestration/Layers/ProviderRuntimeIngestion.test.ts	Updates `ServerConfig.layerTest` calls for new signature.
apps/server/src/orchestration/Layers/ProviderCommandReactor.test.ts	Updates harness to manage temp base dirs and pass `baseDir`.
apps/server/src/orchestration/Layers/ProjectionPipeline.test.ts	Updates projection pipeline test layers to include `baseDir` and temp dir cleanup.
apps/server/src/orchestration/Layers/OrchestrationEngine.test.ts	Updates `ServerConfig.layerTest` calls for new signature.
apps/server/src/orchestration/Layers/CheckpointReactor.test.ts	Updates `ServerConfig.layerTest` calls for new signature.
apps/server/src/main.ts	Adds `--base-dir` + `T3CODE_BASE_DIR` env parsing and resolves base/state dirs with precedence.
apps/server/src/git/Layers/GitManager.test.ts	Provides `ServerConfig` layer to satisfy `GitCore`’s new dependency.
apps/server/src/git/Layers/GitCore.ts	Moves default worktrees directory under `<baseDir>/worktrees`.
apps/server/src/git/Layers/GitCore.test.ts	Provides `ServerConfig` layer for GitCore tests.
apps/server/src/git/Layers/CodexTextGeneration.test.ts	Updates test layer creation to pass `baseDir`/stateDir.
apps/server/src/config.ts	Adds `baseDir` to `ServerConfigShape` and updates `layerTest` signature.
apps/server/integration/OrchestrationEngineHarness.integration.ts	Updates integration harness to pass base dir into test config layer.
apps/desktop/src/main.ts	Derives desktop state dir from `T3CODE_BASE_DIR` and forwards it to backend env.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

scripts/dev-runner.ts

apps/desktop/src/main.ts

apps/server/src/git/Layers/CodexTextGeneration.test.ts

…ncy.

juliusmarminge · 2026-03-10T18:32:35Z

i feel like we have too many flags already 😆, would be down to just have T3_HOME and everything relative to that one?

mcking-07 · 2026-03-10T18:45:50Z

nice, much cleaner... let me confirm the plan,

removing

--base-dir and --state-dir CLI flags
T3CODE_BASE_DIR env var
T3CODE_STATE_DIR env var

introducing

single T3_HOME (or T3CODE_HOME?) env var
--t3-home CLI flag (optional, for convenience)
defaults to ~/.t3
fixed structure:
- $T3_HOME/userdata/ — SQLite, logs, app state
- $T3_HOME/worktrees/ — git worktrees

quick question on naming... should I go with T3_HOME (shorter) or T3CODE_HOME (consistent with T3CODE_PORT, T3CODE_HOST, etc.)?

juliusmarminge · 2026-03-10T18:48:27Z

quick question on naming... should I go with T3_HOME (shorter) or T3CODE_HOME (consistent with T3CODE_PORT, T3CODE_HOST, etc.)?

T3CODE_HOME sounds good. as for cli flag we don't need to have the t3- prefix. just --home-dir (or does that cuas confusion thinking it'll override OS.homedir() ?

mcking-07 · 2026-03-10T18:54:31Z

T3CODE_HOME 👍

or does that cuas confusion thinking it'll override OS.homedir()

--home-dir works for me. it should be clear enough given the context. alternative: --data-dir if you want to avoid any confusion?

…and `--home-dir` flag.

mcking-07 · 2026-03-10T22:15:22Z

@juliusmarminge, i have updated the PR to use the simplified approach we discussed:

changes made:

removed T3CODE_BASE_DIR, T3CODE_STATE_DIR env vars and --base-dir, --state-dir flags
introduced T3CODE_HOME env var and --home-dir flag

behavior:

defaults to ~/.t3
all paths are derived from it:
- dev - dev-runner state (for development mode)
- userdata - app state, sqlite, logs
- worktrees - git worktrees

binbandit · 2026-03-10T22:23:34Z

Can we update the pr title based on the current solution please

binbandit · 2026-03-11T00:12:22Z

Lets change the title to: feat: added configurable base directory -- short sharp clean.

juliusmarminge · 2026-03-20T18:19:10Z

description is outdated?

Note: If stateDir is set explicitly (via CLI or env), it takes full priority and can be anywhere, independent of baseDir.

looks to me like we replace stateDir, correct?

…ter tests.

mcking-07 · 2026-03-20T18:31:38Z

description is outdated?

yes, description is outdated, #826 (comment) would be updated description...

juliusmarminge · 2026-03-20T21:44:57Z

@macroscope-app review this

Mohammed Muzammil Anwar and others added 2 commits March 10, 2026 23:18

feat: add configurable base directory (~/.t3) with `T3CODE_BASE_DIR…

076e2b5

…` env and --base-dir flag.

feat: add configurable base directory (~/.t3) with `T3CODE_BASE_DIR…

bef33cb

…` env and --base-dir flag.

Copilot AI review requested due to automatic review settings March 10, 2026 18:12

github-actions bot added the vouch:unvouched PR author is not yet trusted in the VOUCHED list. label Mar 10, 2026

Copilot started reviewing on behalf of mcking-07 March 10, 2026 18:13 View session

Copilot AI reviewed Mar 10, 2026

View reviewed changes

scripts/dev-runner.ts Outdated Show resolved Hide resolved

apps/desktop/src/main.ts Outdated Show resolved Hide resolved

apps/server/src/git/Layers/CodexTextGeneration.test.ts Outdated Show resolved Hide resolved

Mohammed Muzammil Anwar and others added 2 commits March 11, 2026 00:01

fix: use path.join for constructing state directory path for consiste…

68c2267

…ncy.

Merge branch 'pingdotgg:main' into main

dc8a93b

feat: simplify base directory config to single T3CODE_HOME env var …

b76be31

…and `--home-dir` flag.

mcking-07 changed the title ~~feat: add configurable base directory (~/.t3) with T3CODE_BASE_DIR env and --base-dir flag. Fixes #748~~ feat: add configurable base directory (~/.t3) with T3CODE_HOME env and --home-dir flag. Fixes #748 Mar 10, 2026

mcking-07 changed the title ~~feat: add configurable base directory (~/.t3) with T3CODE_HOME env and --home-dir flag. Fixes #748~~ feat: added configurable base directory. Mar 11, 2026

Mohammed Muzammil Anwar and others added 2 commits March 11, 2026 22:12

enhance state directory resolution to handle dev mode.

b1cb068

Merge branch 'main' into main

e245aeb

github-actions bot added the size:L 100-499 changed lines (additions + deletions). label Mar 13, 2026

maria-rcks requested a review from juliusmarminge March 15, 2026 19:53

mcking-07 added 2 commits March 19, 2026 01:54

Merge branch 'main' into main

6de5527

Merge branch 'main' into main

721a51a

fix(tests): add baseDir option to makeHarness function to claude adap…

517c1ef

…ter tests.

remove state dir and add derivation helpers

1dca637

github-actions bot removed the size:L 100-499 changed lines (additions + deletions). label Mar 20, 2026

github-actions bot added the size:XXL 1,000+ changed lines (additions + deletions). label Mar 20, 2026

juliusmarminge added 2 commits March 20, 2026 14:42

simp

cd906ee

nit

4200a39

juliusmarminge added 2 commits March 20, 2026 14:59

cool

5d09b38

lint

1b462fd

juliusmarminge merged commit 9e29c9d into pingdotgg:main Mar 20, 2026
8 of 9 checks passed

Conversation

mcking-07 commented Mar 10, 2026 • edited by macroscopeapp bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What Changed

Why

Checklist

Replace --state-dir/T3CODE_STATE_DIR with --home-dir/T3CODE_HOME as the configurable base directory

Uh oh!

coderabbitai bot commented Mar 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review skipped

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

juliusmarminge commented Mar 10, 2026

Uh oh!

mcking-07 commented Mar 10, 2026

Uh oh!

juliusmarminge commented Mar 10, 2026

Uh oh!

mcking-07 commented Mar 10, 2026

Uh oh!

mcking-07 commented Mar 10, 2026

Uh oh!

binbandit commented Mar 10, 2026

Uh oh!

binbandit commented Mar 11, 2026

Uh oh!

juliusmarminge commented Mar 20, 2026

Uh oh!

mcking-07 commented Mar 20, 2026

Uh oh!

juliusmarminge commented Mar 20, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

mcking-07 commented Mar 10, 2026 •

edited by macroscopeapp bot

Loading

Replace `--state-dir`/`T3CODE_STATE_DIR` with `--home-dir`/`T3CODE_HOME` as the configurable base directory

coderabbitai bot commented Mar 10, 2026 •

edited

Loading